home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / MDB / QueryTool / Query.php < prev    next >
PHP Script  |  2004-03-24  |  74KB  |  2,037 lines
  1. <?php
  2. // +----------------------------------------------------------------------+
  3. // | PHP Version 4                                                        |
  4. // +----------------------------------------------------------------------+
  5. // | Copyright (c) 1997-2003 The PHP Group                                |
  6. // +----------------------------------------------------------------------+
  7. // | This source file is subject to version 2.02 of the PHP license,      |
  8. // | that is bundled with this package in the file LICENSE, and is        |
  9. // | available at through the world-wide-web at                           |
  10. // | http://www.php.net/license/2_02.txt.                                 |
  11. // | If you did not receive a copy of the PHP license and are unable to   |
  12. // | obtain it through the world-wide-web, please send a note to          |
  13. // | license@php.net so we can mail you a copy immediately.               |
  14. // +----------------------------------------------------------------------+
  15. // | Author: Lorenzo Alberton <l.alberton at quipo.it>                    |
  16. // +----------------------------------------------------------------------+
  17. //
  18. // $Id: Query.php,v 1.25 2004/03/19 01:07:02 quipo Exp $
  19. //
  20. // This is just a port of DB_QueryTool, originally written by
  21. // Wolfram Kriesing and Paolo Panto, vision:produktion <wk@visionp.de>
  22. // All the praises go to them :)
  23. //
  24.  
  25. require_once 'PEAR.php';
  26. require_once 'MDB.php';
  27.  
  28.  
  29. /**
  30.  * this class should be extended
  31.  *
  32.  * @package  MDB_QueryTool
  33.  * @access   public
  34.  * @author   Lorenzo Alberton
  35.  */
  36. class MDB_QueryTool_Query
  37. {
  38.  
  39.     /**
  40.      * @var string  the name of the primary column
  41.      */
  42.     var $primaryCol = 'id';
  43.  
  44.     /**
  45.      * @var string  the current table the class works on
  46.      */
  47.     var $table      = '';
  48.  
  49.     /**
  50.      * @var string  the name of the sequence for this table
  51.      */
  52.     var $sequenceName = null;
  53.  
  54.     /**
  55.      * @var object  the db-object, a PEAR::Mdb-object instance
  56.      */
  57.     var $db = null;
  58.  
  59.     /**
  60.      * @var string  the where condition
  61.      * @access private
  62.      */
  63.     var $_where = '';
  64.  
  65.     /**
  66.      * @var string  the order condition
  67.      * @access private
  68.      */
  69.     var $_order = '';
  70.  
  71.     /**
  72.      * @var    string  the having definition
  73.      * @access private
  74.      */
  75.     var $_having = '';
  76.  
  77.     /**
  78.      * @var array  contains the join content
  79.      *             the key is the join type, for now we have 'default' and 'left'
  80.      *             inside each key 'table' contains the table
  81.      *                         key 'where' contains the where clause for the join
  82.      * @access private
  83.      */
  84.     var $_join = array();
  85.  
  86.     /**
  87.      * @var string  which column to index the result by
  88.      * @access private
  89.      */
  90.     var $_index = null;
  91.  
  92.     /**
  93.      * @var string  the group-by clause
  94.      * @access private
  95.      */
  96.     var $_group = '';
  97.  
  98.     /**
  99.      * @var array   the limit
  100.      * @access private
  101.      */
  102.     var $_limit = array();
  103.  
  104.     /**
  105.      * @var boolean     if to use the MDB_QueryTool_Result as a result or not
  106.      * @access private
  107.      */
  108.     var $_useResult = false;
  109.  
  110.     /**
  111.      * @var array       the metadata temporary saved
  112.      * @access private
  113.      */
  114.     var $_metadata = array();
  115.  
  116.     /**
  117.      * @var string (?)
  118.      * @access private
  119.      */
  120.     var $_lastQuery = null;
  121.  
  122.     /**
  123.      * @var string the rows that shall be selected
  124.      * @access private
  125.      */
  126.     var $_select = '*';
  127.  
  128.     /**
  129.      * @var string
  130.      * @access private
  131.      */
  132.     var $_dontSelect = '';
  133.  
  134.     /**
  135.      * @var array   this array saves different modes in which this class works
  136.      *              i.e. 'raw' means no quoting before saving/updating data
  137.      * @access private
  138.      */
  139.     var $options = array(   'raw'       =>  false,
  140.                             'verbose'   =>  true,       // set this to false in a productive environment
  141.                                                         // it will produce error-logs if set to true
  142.                             'useCache' =>  false,
  143.                             'logFile'  =>  false
  144.  
  145.                         );
  146.  
  147.     /**
  148.      * this array contains information about the tables
  149.      * those are
  150.      *         'name' -        the real table name
  151.      *         'shortName' -   the short name used, so that when moving the table i.e.
  152.      *                         onto a provider's db and u have to rename the tables to longer names
  153.      *                         this name will be relevant, i.e. when autoJoining, i.e. a table name
  154.      *                         on your local machine is: 'user' but online it has to be 'applName_user'
  155.      *                         then the shortName will be used to determine if a column refers to another
  156.      *                         table, if the colName is 'user_id', it knows the shortName 'user' refers to the table
  157.      *                         'applName_user'
  158.      */
  159.     var $tableSpec = array();
  160.  
  161.     /**
  162.      * this is the regular expression that shall be used to find a table's shortName
  163.      * in a column name, the string found by using this regular expression will be removed
  164.      * from the column name and it will be checked if it is a table name
  165.      * i.e. the default '/_id$/' would find the table name 'user' from the column name 'user_id'
  166.      *
  167.      * @access private
  168.      */
  169.     var $_tableNameToShortNamePreg = '/^.*_/';
  170.  
  171.     /**
  172.      * var array  this array caches queries that have already been built once
  173.      *            to reduce the execution time
  174.      * @access private
  175.      */
  176.     var $_queryCache = array();
  177.  
  178.  
  179.     /**
  180.      * The object that contains the log-instance
  181.      * @access private
  182.      */
  183.     var $_logObject = null;
  184.  
  185.     /**
  186.      * Some internal data the logging needs
  187.      * @access private
  188.      */
  189.     var $_logData = array();
  190.  
  191.  
  192.     /**
  193.      * this is the constructor, as it will be implemented in ZE2 (php5)
  194.      *
  195.      * @param   object  db-object
  196.      * @param   array   options array
  197.      * @access  public
  198.      */
  199. /*
  200.     function __construct($dsn=false, $options=array())
  201.     {
  202.         if (!isset($options['autoConnect'])) {
  203.             $autoConnect = true;
  204.         } else {
  205.             $autoConnect = $options['autoConnect'];
  206.         }
  207.         if (isset($options['errorCallback'])) {
  208.             $this->setErrorCallback($options['errorCallback']);
  209.         }
  210.         if (isset($options['errorSetCallback'])) {
  211.             $this->setErrorSetCallback($options['errorSetCallback']);
  212.         }
  213.         if (isset($options['errorLogCallback'])) {
  214.             $this->setErrorLogCallback($options['errorLogCallback']);
  215.         }
  216.  
  217.         if ($autoConnect && $dsn) {
  218.             $this->connect($dsn, $options);
  219.         }
  220.  
  221.         if (is_null($this->sequenceName)) {
  222.             $this->sequenceName = $this->table;
  223.         }
  224.     }
  225. */
  226.  
  227.     /**
  228.      * @param mixed $dsn DSN string, DSN array or MDB object
  229.      * @param array $options
  230.      * @access  public
  231.      */
  232.     function MDB_QueryTool_Query($dsn=false, $options=array())
  233.     {
  234.         //$this->__construct($dsn, $options);
  235.  
  236.         if (!isset($options['autoConnect'])) {
  237.             $autoConnect = true;
  238.         } else {
  239.             $autoConnect = $options['autoConnect'];
  240.         }
  241.         if (isset($options['errorCallback'])) {
  242.             $this->setErrorCallback($options['errorCallback']);
  243.         }
  244.         if (isset($options['errorSetCallback'])) {
  245.             $this->setErrorSetCallback($options['errorSetCallback']);
  246.         }
  247.         if (isset($options['errorLogCallback'])) {
  248.             $this->setErrorLogCallback($options['errorLogCallback']);
  249.         }
  250.  
  251.         if ($autoConnect && $dsn) {
  252.             $this->connect($dsn, $options);
  253.         }
  254.  
  255.         if (is_null($this->sequenceName)) {
  256.             $this->sequenceName = $this->table;
  257.         }
  258.     }
  259.  
  260.     /**
  261.      * use this method if you want to connect manually
  262.      * @param mixed $dsn DSN string, DSN array or MDB object
  263.      * @param array $options
  264.      */
  265.     function connect($dsn, $options=array())
  266.     {
  267.         $res = $this->db = &MDB::connect($dsn, $options);
  268.         if (MDB::isError($res)) {
  269.     // FIXXME what shall we do here?
  270.             $this->_errorLog($res->getUserInfo());
  271.         } else {
  272.             $this->db->setFetchMode(MDB_FETCHMODE_ASSOC);
  273.         }
  274.     }
  275.  
  276.     /**
  277.      *   @return  object MDB Object
  278.      *   @access  public
  279.      */
  280.     function &getDbInstance()
  281.     {
  282.         return $this->db;
  283.     }
  284.  
  285.     /**
  286.      * Setup using an existing connection.
  287.      * this also sets the MDB_FETCHMODE_ASSOC since this class
  288.      * needs this to be set!
  289.      *
  290.      * @param object a reference to an existing DB-object
  291.      * @return void
  292.      */
  293.     function setDbInstance( &$dbh)
  294.     {
  295.         $this->db =& $dbh;
  296.         $this->db->setFetchMode(MDB_FETCHMODE_ASSOC);
  297.     }
  298.  
  299.     /**
  300.      * get the data of a single entry
  301.      * if the second parameter is only one column the result will be returned
  302.      * directly not as an array!
  303.      *
  304.      *   @param   integer the id of the element to retreive
  305.      *   @param   string  if this is given only one row shall be returned,
  306.      *                    directly, not an array
  307.      *   @return  mixed   (1) an array of the retreived data
  308.      *                    (2) if the second parameter is given and its only one column,
  309.      *                        only this column's data will be returned
  310.      *                    (3) false in case of failure
  311.      *   @access  public
  312.      */
  313.     function get($id, $column='')
  314.     {
  315.         $id     = trim($id);
  316.         $column = trim($column);
  317.         $table  = $this->table;
  318.         $getMethod = 'getRow';
  319.         if ($column && !strpos($column, ',')) {    // if only one column shall be selected
  320.             $getMethod = 'getOne';
  321.         }
  322.         // we dont use 'setSelect' here, since this changes the setup of the class, we
  323.         // build the query directly
  324.         // if $column is '' then _buildSelect selects '*' anyway, so that's the same behaviour as before
  325.         $query['select'] = $this->_buildSelect($column);
  326.         $query['where']  = $this->_buildWhere($this->table.'.'.$this->primaryCol.'='.$this->_quote($id));
  327.         $queryString     = $this->_buildSelectQuery($query);
  328.  
  329.         return $this->returnResult($this->execute($queryString, $getMethod));
  330.     }
  331.  
  332.     /**
  333.      * gets the data of the given ids
  334.      *
  335.      * @param   array   this is an array of ids to retreive
  336.      * @param   string  the column to search in for
  337.      * @return  mixed   an array of the retreived data, or false in case of failure
  338.      *                  when failing an error is set in $this->_error
  339.      * @access  public
  340.      */
  341.     function getMultiple($ids, $column='')
  342.     {
  343.         $col = $this->primaryCol;
  344.         if ($column) {
  345.             $col = $column;
  346.         }
  347. // FIXXME if $ids has no table.col syntax and we are using joins, the table better be put in front!!!
  348.         $ids = $this->_quoteArray($ids);
  349.  
  350.         $query['where'] = $this->_buildWhere($col.' IN ('.implode(',', $ids).')');
  351.         $queryString    = $this->_buildSelectQuery($query);
  352.  
  353.         return $this->returnResult($this->execute($queryString));
  354.     }
  355.  
  356.     /**
  357.      * get all entries from the DB
  358.      * for sorting use setOrder!!!, the last 2 parameters are deprecated
  359.      *
  360.      * @param   int     to start from
  361.      * @param   int     the number of rows to show
  362.      * @return  mixed   an array of the retreived data, or false in case of failure
  363.      *                  when failing an error is set in $this->_error
  364.      * @access  public
  365.      */
  366.     function getAll($from=0, $count=0, $method='getAll')
  367.     {
  368.         $query = array();
  369.         if ($count) {
  370.             $query = array('limit' => array($from, $count));
  371.         }
  372.         return $this->returnResult($this->execute($this->_buildSelectQuery($query), $method));
  373.     }
  374.  
  375.     /**
  376.      * this method only returns one column, so the result will be a one dimensional array
  377.      * this does also mean that using setSelect() should be set to *one* column, the one you want to
  378.      * have returned a most common use case for this could be:
  379.      *     $table->setSelect('id');
  380.      *     $ids = $table->getCol();
  381.      * OR
  382.      *     $ids = $table->getCol('id');
  383.      * so ids will ba an array with all the id's
  384.      *
  385.      * @param   string  the column that shall be retreived
  386.      * @param   int     to start from
  387.      * @param   int     the number of rows to show
  388.      * @return  mixed   an array of the retreived data, or false in case of failure
  389.      *                  when failing an error is set in $this->_error
  390.      * @access  public
  391.      */
  392.     function getCol($column=null, $from=0, $count=0)
  393.     {
  394.         $query = array();
  395.         if ($column != null) {
  396.             // by using _buildSelect() I can be sure that the table name will not be ambiguous
  397.             // i.e. in a join, where all the joined tables have a col 'id'
  398.             // _buildSelect() will put the proper table name in front in case there is none
  399.             $query['select'] = $this->_buildSelect(trim($column));
  400.         }
  401.         if ($count) {
  402.             $query['limit'] = array($from, $count);
  403.         }
  404.         return $this->returnResult($this->execute($this->_buildSelectQuery($query), 'getCol'));
  405.     }
  406.  
  407.     /**
  408.      * get the number of entries
  409.      *
  410.      * @return  mixed   an array of the retreived data, or false in case of failure
  411.      *                  when failing an error is set in $this->_error
  412.      * @access  public
  413.      */
  414.     function getCount()
  415.     {
  416. /* the following query works on mysql
  417. SELECT count(DISTINCT image.id) FROM image2tree
  418. RIGHT JOIN image ON image.id = image2tree.image_id
  419. the reason why this is needed - i just wanted to get the number of rows that do exist if the result is grouped by image.id
  420. the following query is what i tried first, but that returns the number of rows that have been grouped together
  421. for each image.id
  422. SELECT count(*) FROM image2tree
  423. RIGHT JOIN image ON image.id = image2tree.image_id GROUP BY image.id
  424.  
  425. so that's why we do the following, i am not sure if that is standard SQL and absolutley correct!!!
  426. */
  427.  
  428. //FIXXME see comment above if this is absolutely correct!!!
  429.         if ($group = $this->_buildGroup()) {
  430.             $query['select'] = 'COUNT(DISTINCT '.$group.')';
  431.             $query['group']  = '';
  432.         } else {
  433.             $query['select'] = 'COUNT(*)';
  434.         }
  435.  
  436.         $query['order'] = '';   // order is not of importance and might freak up the special group-handling up there, since the order-col is not be known
  437. /*# FIXXME use the following line, but watch out, then it has to be used in every method, or this
  438. # value will be used always, simply try calling getCount and getAll afterwards, getAll will return the count :-)
  439. # if getAll doenst use setSelect!!!
  440. */
  441.         //$this->setSelect('count(*)');
  442.         $queryString = $this->_buildSelectQuery($query);
  443.         return($res=$this->execute($queryString, 'getOne')) ? $res : 0;
  444.     }
  445.  
  446.     /**
  447.      * return an empty element where all the array elements do already exist
  448.      * corresponding to the columns in the DB
  449.      *
  450.      * @return  array   an empty, or pre-initialized element
  451.      * @access  public
  452.      */
  453.     function getDefaultValues()
  454.     {
  455.         $ret = array();
  456.         // here we read all the columns from the DB and initialize them
  457.         // with '' to prevent PHP-warnings in case we use error_reporting=E_ALL
  458.         foreach ($this->metadata() as $aCol => $x) {
  459.             $ret[$aCol] = '';
  460.         }
  461.         return $ret;
  462.     }
  463.  
  464.     /**
  465.      * this is just for BC
  466.      * @deprecated
  467.      */
  468.     function getEmptyElement()
  469.     {
  470.         $this->getDefaultValues();
  471.     }
  472.  
  473.     /**
  474.      * Render the current query and return it as a string.
  475.      *
  476.      * @return string the current query
  477.      */
  478.     function getQueryString()
  479.     {
  480.         $ret = $this->_buildSelectQuery();
  481.         if (is_string($ret)) {
  482.             $ret = trim($ret);
  483.         }
  484.         return $ret;
  485.     }
  486.  
  487.     /**
  488.      * save data, calls either update or add
  489.      * if the primaryCol is given in the data this method knows that the
  490.      * data passed to it are meant to be updated (call 'update'), otherwise it will
  491.      * call the method 'add'.
  492.      * If you dont like this behaviour simply stick with the methods 'add'
  493.      * and 'update' and ignore this one here.
  494.      * This method is very useful when you have validation checks that have to
  495.      * be done for both adding and updating, then you can simply overwrite this
  496.      * method and do the checks in here, and both cases will be validated first.
  497.      *
  498.      * @param   array   contains the new data that shall be saved in the DB
  499.      * @return  mixed   the data returned by either add or update-method
  500.      * @access  public
  501.      */
  502.     function save($data)
  503.     {
  504.         if (isset($data[$this->primaryCol]) && $data[$this->primaryCol]) {
  505.             return $this->update($data);
  506.         }
  507.         return $this->add($data);
  508.     }
  509.  
  510.     /**
  511.      * update the member data of a data set
  512.      *
  513.      * @param   array   contains the new data that shall be saved in the DB
  514.      *                  the id has to be given in the field with the key 'ID'
  515.      * @return  mixed   true on success, or false otherwise
  516.      * @access  public
  517.      */
  518.     function update($newData)
  519.     {
  520.         $query = array();
  521.         // do only set the 'where' part in $query, if a primary column is given
  522.         // if not the default 'where' clause is used
  523.         if (isset($newData[$this->primaryCol])) {
  524.             //$this->_errorSet('Error updating the new member.');
  525.             //return false;
  526.             $query['where'] = $this->primaryCol.'='.$this->_quote($newData[$this->primaryCol]);
  527.         }
  528.  
  529.         $newData = $this->_checkColumns($newData, 'update');
  530.         $values = array();
  531.         foreach ($newData as $key => $aData) {   // quote the data
  532.             //$values[] = "{$this->table}.$key=" . $this->_quote($aData);
  533.             $values[] = "$key=" . $this->_quote($aData);
  534.         }
  535.  
  536.         $query['set'] = implode(',', $values);
  537.         $updateString = $this->_buildUpdateQuery($query);
  538.         return $this->execute($updateString, 'query') ? true : false;
  539.     }
  540.  
  541.     /**
  542.      * add a new member in the DB
  543.      *
  544.      * @param   array   contains the new data that shall be saved in the DB
  545.      * @return  mixed   the inserted id on success, or false otherwise
  546.      * @access  public
  547.      */
  548.     function add($newData)
  549.     {
  550.         unset($newData[$this->primaryCol]);
  551.  
  552.         $newData = $this->_checkColumns($newData,'add');
  553.         $newData = $this->_quoteArray($newData);
  554.  
  555.         if ($this->primaryCol) { // do only use the sequence if a primary column is given
  556.                                 // otherwise the data are written as given
  557.             $id = (int)$this->db->nextId($this->sequenceName);
  558.             $newData[$this->primaryCol] = (int)$id;
  559.         } else {
  560.             // if no primary col is given return true on success
  561.             $id = true;
  562.         }
  563.  
  564.         $query = sprintf( 'INSERT INTO %s (%s) VALUES (%s)',
  565.                           $this->table,
  566.                           implode(',', array_keys($newData)),
  567.                           implode(',', $newData)
  568.                         );
  569.         return $this->execute($query, 'query') ? $id : false;
  570.     }
  571.  
  572.     /**
  573.      * adds multiple new members in the DB
  574.      *
  575.      * @param   array   contains an array of new data that shall be saved in the DB
  576.      *                  the key-value pairs have to be the same for all the data!!!
  577.      * @return  mixed   the inserted ids on success, or false otherwise
  578.      * @access  public
  579.      */
  580.     function addMultiple($data)
  581.     {
  582.         if (!sizeof($data)) {
  583.             return false;
  584.         }
  585.         // the inserted ids which will be returned or if no primaryCol is given
  586.         // we return true by default
  587.         $retIds = $this->primaryCol ? array() : true;
  588.         $allData = array();                     // each row that will be inserted
  589.         foreach ($data as $key => $aData) {
  590.             unset($aData[$this->primaryCol]);   // we are adding a new data set, so be sure
  591.                                                 // there is no value for the primary col
  592.             $aData = $this->_checkColumns($aData,'add');
  593.             $aData = $this->_quoteArray($aData);
  594.  
  595.             // do only use the sequence if a primary column is given
  596.             // otherwise the data are written as given
  597.             if ($this->primaryCol) {
  598.                 $id = $this->db->nextId($this->sequenceName);
  599.                 $aData[$this->primaryCol] = $this->_quote($id);
  600.  
  601.                 $retIds[] = $id;
  602.             }
  603.             $allData[] = '('.implode(',', $aData).')';
  604.         }
  605.  
  606.         $query = sprintf( 'INSERT INTO %s (%s) VALUES %s',
  607.                           $this->table ,
  608.                           implode(',', array_keys($aData)) ,
  609.                           implode(',', $allData)
  610.                         );
  611.         return $this->execute($query, 'query') ? $retIds : false;
  612.     }
  613.  
  614.     /**
  615.      * removes a member from the DB
  616.      *
  617.      * @param   mixed   integer/string - the value of the column that shall be removed
  618.      *                  array   - multiple columns that shall be matched, the second parameter will be ommited
  619.      * @param   string  the column to match the data against, only if $data is not an array
  620.      * @return  boolean
  621.      * @access  public
  622.      */
  623.     function remove($data, $whereCol='')
  624.     {
  625.         //$raw = $this->getOption('raw');
  626.  
  627.         if (is_array($data)) {
  628. //FIXXME check $data if it only contains columns that really exist in the table
  629.             $wheres = array();
  630.             foreach ($data as $key => $val) {
  631.                 $wheres[] = $key .'='. $this->_quote($val);
  632.             }
  633.             $whereClause = implode(' AND ', $wheres);
  634.         } else {
  635.             if ($whereCol=='') {
  636.                 $whereCol = $this->primaryCol;
  637.             }
  638.             $whereClause = $whereCol.'='. $this->_quote($data);
  639.         }
  640.  
  641.         $query = sprintf( 'DELETE FROM %s WHERE %s',
  642.                           $this->table,
  643.                           $whereClause
  644.                           );
  645.         return $this->execute($query, 'query') ? true : false;
  646. // i think this method should return the ID's that it removed, this way we could simply use the result
  647. // for further actions that depend on those id ... or? make stuff easier, see ignaz::imail::remove
  648.     }
  649.  
  650.     /**
  651.      * empty a table
  652.      *
  653.      * @return resultSet or false on error [execute() result]
  654.      * @access public
  655.      */
  656.     function removeAll()
  657.     {
  658.         $query = 'DELETE FROM ' . $this->table;
  659.         return $this->execute($query, 'query') ? true : false;
  660.     }
  661.  
  662.     /**
  663.      * remove the datasets with the given ids
  664.      *
  665.      * @param  array   the ids to remove
  666.      * @return resultSet or false on error [execute() result]
  667.      * @access public
  668.      */
  669.     function removeMultiple($ids, $colName='')
  670.     {
  671.         if ($colName=='') {
  672.             $colName = $this->primaryCol;
  673.         }
  674.         $ids = $this->_quoteArray($ids);
  675.  
  676.         $query = sprintf( 'DELETE FROM %s WHERE %s IN (%s)',  //IS THIS PORTABLE???????????????????
  677.                           $this->table,
  678.                           $colName,
  679.                           implode(',', $ids)
  680.                         );
  681.         return $this->execute($query, 'query') ? true : false;
  682.     }
  683.  
  684.     /**
  685.      * removes a member from the DB and calls the remove methods of the given objects
  686.      * so all rows in another table that refer to this table are erased too
  687.      *
  688.      * @param   integer the value of the primary key
  689.      * @param   string  the column name of the tables with the foreign keys
  690.      * @param   object  just for convinience, so nobody forgets to call this method
  691.      *                  with at least one object as a parameter
  692.      * @return  boolean
  693.      * @access  public
  694.      */
  695.     function removePrimary($id, $colName, $atLeastOneObject)
  696.     {
  697.         $argCounter = 2;    // we have 2 parameters that need to be given at least
  698.         // func_get_arg returns false and a warning if there are no more parameters, so
  699.         // we suppress the warning and check for false
  700.         while($object=@func_get_arg($argCounter++)) {
  701. //FIXXXME let $object also simply be a table name
  702.             if (!$object->remove($id, $colName)) {
  703. //FIXXXME do this better
  704.                 $this->_errorSet("Error removing '$colName=$id' from table {$object->table}.");
  705.                 return false;
  706.             }
  707.         }
  708.  
  709.         if (!$this->remove($id)) {
  710.             return false;
  711.         }
  712.         return true;
  713.     }
  714.  
  715.     /**
  716.      * sets query limits
  717.      *
  718.      * @param   integer $from   start index
  719.      * @param   integer $count  number of results
  720.      * @access  public
  721.      */
  722.     function setLimit($from=0, $count=0)
  723.     {
  724.         if ($from==0 && $count==0) {
  725.             $this->_limit = array();
  726.         } else {
  727.             $this->_limit = array($from, $count);
  728.         }
  729.     }
  730.  
  731.     /**
  732.      * gets query limits
  733.      *
  734.      * @return array (start index, number of results)
  735.      * @access  public
  736.      */
  737.     function getLimit()
  738.     {
  739.         return $this->_limit;
  740.     }
  741.  
  742.  
  743.     /**
  744.      * sets the where condition which is used for the current instance
  745.      *
  746.      * @param   string  the where condition, this can be complete like 'X=7 AND Y=8'
  747.      * @access  public
  748.      */
  749.     function setWhere($whereCondition='')
  750.     {
  751.         $this->_where = $whereCondition;
  752. //FIXXME parse the where condition and replace ambigious column names, such as "name='Deutschland'" with "country.name='Deutschland'"
  753. // then the users dont have to write that explicitly and can use the same name as in the setOrder i.e. setOrder('name,_net_name,_netPrefix_prefix');
  754.     }
  755.  
  756.     /**
  757.      *   gets the where condition which is used for the current instance
  758.      *
  759.      *   @return  string  the where condition, this can be complete like 'X=7 AND Y=8'
  760.      *   @access  public
  761.      */
  762.     function getWhere()
  763.     {
  764.         return $this->_where;
  765.     }
  766.  
  767.     /**
  768.      *   only adds a string to the where clause
  769.      *
  770.      *   @param   string  the where clause to add to the existing one
  771.      *   @param   string  the condition for how to concatenate the new where clause
  772.      *                    to the existing one
  773.      *   @access  public
  774.      */
  775.     function addWhere($where , $condition='AND')
  776.     {
  777.         if ($this->getWhere()) {
  778.             $where = $this->getWhere().' '.$condition.' '.$where;
  779.         }
  780.         $this->setWhere($where);
  781.     }
  782.  
  783.     /**
  784.      * add a where-like clause which works like a search for the given string
  785.      * i.e. calling it like this:
  786.      *     $this->addWhereSearch('name', 'otto hans')
  787.      * produces a where clause like this one
  788.      *     LOWER(name) LIKE "%otto%hans%"
  789.      * so the search finds the given string
  790.      *
  791.      * @param   string  the column to search in for
  792.      * @param   string  the string to search for
  793.      * @access  public
  794.      */
  795.     function addWhereSearch($column, $string, $condition='AND')
  796.     {
  797.         // if the column doesnt contain a tablename use the current table name in case it is a defined column
  798.         // to prevent ambigious rows
  799.         if (strpos($column, '.') === false) {
  800.             $meta = $this->metadata();
  801.             if (isset($meta[$column])) {
  802.                 $column = $this->table .'.'. trim($column);
  803.             }
  804.         }
  805.  
  806.         $string = $this->_quote('%'.str_replace(' ', '%', strtolower($string)).'%');
  807.         $this->addWhere("LOWER($column) LIKE $string", $condition);
  808.     }
  809.  
  810.     /**
  811.      * sets the order condition which is used for the current instance
  812.      *
  813.      * @param   string  the where condition, this can be complete like 'X=7 AND Y=8'
  814.      * @access  public
  815.      */
  816.     function setOrder($orderCondition='', $desc=false)
  817.     {
  818.         $this->_order = $orderCondition . ($desc ? ' DESC' : '');
  819.     }
  820.  
  821.     /**
  822.      * Add a order parameter to the query.
  823.      *
  824.      * @param  string  the where condition, this can be complete like 'X=7 AND Y=8'
  825.      * @access public
  826.      */
  827.     function addOrder($orderCondition='', $desc=false)
  828.     {
  829.         $order = $orderCondition . ($desc ? ' DESC' : '');
  830.         if ($this->_order) {
  831.             $this->_order = $this->_order .','. $order;
  832.         } else {
  833.             $this->_order = $order;
  834.         }
  835.     }
  836.  
  837.     /**
  838.      * gets the order condition which is used for the current instance
  839.      *
  840.      * @return  string  the order condition, this can be complete like 'ID,TIMESTAMP DESC'
  841.      * @access  public
  842.      */
  843.     function getOrder()
  844.     {
  845.         return $this->_order;
  846.     }
  847.  
  848.     /**
  849.      * sets the having definition
  850.      *
  851.      * @param  string  the having definition
  852.      * @access public
  853.      */
  854.     function setHaving($having='')
  855.     {
  856.         $this->_having = $having;
  857.     }
  858.  
  859.     /**
  860.      * gets the having definition which is used for the current instance
  861.      *
  862.      * @return string  the having definition
  863.      * @access public
  864.      */
  865.     function getHaving()
  866.     {
  867.         return $this->_having;
  868.     }
  869.  
  870.     /**
  871.      * Extend the current having clause. This is very useful, when you are building
  872.      * this clause from different places and dont want to overwrite the currently
  873.      * set having clause, but extend it.
  874.      *
  875.      * @param string this is a having clause, i.e. 'column' or 'table.column' or 'MAX(column)'
  876.      * @param string the connection string, which usually stays the default, which is ',' (a comma)
  877.      * @access public
  878.      */
  879.     function addHaving($what='*', $connectString=' AND ')
  880.     {
  881.         if ($this->_having) {
  882.             $this->_having = $this->_having . $connectString . $what;
  883.         } else {
  884.             $this->_having = $what;
  885.         }
  886.     }
  887.  
  888.     /**
  889.      * sets a join-condition
  890.      *
  891.      * @param   mixed   either a string or an array that contains
  892.      *                  the table(s) to join on the current table
  893.      * @param   string  the where clause for the join
  894.      * @access  public
  895.      */
  896.     function setJoin($table=null, $where=null, $joinType='default')
  897.     {
  898. //FIXXME make it possible to pass a table name as a string like this too 'user u' where u is the string that can be used
  899. // to refer to this table in a where/order or whatever condition
  900. // this way it will be possible to join tables with itself, like setJoin(array('user u', 'user u1'))
  901. // this wouldnt work yet, but for doing so we would need to change the _build methods too!!!
  902. // because they use getJoin('tables') and this simply returns all the tables in use but dont take care of the mentioned syntax
  903.  
  904.         if ($table==null || $where==null) {            // remove the join if not sufficient parameters are given
  905.             $this->_join[$joinType] = array();
  906.             return;
  907.         }
  908.  
  909.         settype($table, 'array');
  910.         $this->_join[$joinType]['table'] = $table;
  911. /* this causes problems if we use the order-by, since it doenst know the name to order it by ... :-)
  912.         // replace the table names with the internal name used for the join
  913.         // this way we can also join one table multiple times if it will be implemented one day
  914.         $this->_join['where'] = preg_replace('/'.$table.'/','j1', $where);
  915. */
  916.         $this->_join[$joinType]['where'] = $where;
  917.     }
  918.  
  919.     /**
  920.      * if you do a left join on $this->table you will get all entries
  921.      * from $this->table, also if there are no entries for them in the joined table
  922.      * if both parameters are not given the left-join will be removed
  923.      * NOTE: be sure to only use either a right or a left join
  924.      *
  925.      * @param   string  the table(s) to be left-joined
  926.      * @param   string  the where clause for the join
  927.      * @access  public
  928.      */
  929.     function setLeftJoin($table=null, $where=null)
  930.     {
  931.         $this->setJoin($table, $where, 'left');
  932.     }
  933.  
  934.     /**
  935.      *
  936.      * @param  string  the table(s) to be left-joined
  937.      * @param  string  the where clause for the join
  938.      * @param  string  join type
  939.      * @access public
  940.      */
  941.     function addLeftJoin($table, $where, $type='left')
  942.     {
  943.         // init value, to prevent E_ALL-warning
  944.         if (!isset($this->_join[$type]) || !$this->_join[$type]) {
  945.             $this->_join[$type] = array('table' => array(),
  946.                                         'where' => '');
  947.         }
  948.         $this->_join[$type]['table'] = array_merge($this->_join[$type]['table'], $table);
  949.         if (!is_array($this->_join[$type]['where'])) {
  950.             settype($this->_join[$type]['where'], 'array');
  951.         }
  952.         $this->_join[$type]['where'][] = $where;
  953.     }
  954.  
  955.     /**
  956.      * see setLeftJoin for further explaination on what a left/right join is
  957.      * NOTE: be sure to only use either a right or a left join
  958. //FIXXME check if the above sentence is necessary and if sql doesnt allow the use of both
  959.      *
  960.      * @param   string  the table(s) to be right-joined
  961.      * @param   string  the where clause for the join
  962.      * @see     setLeftJoin()
  963.      * @access  public
  964.      */
  965.     function setRightJoin($table=null, $where=null)
  966.     {
  967.         $this->setJoin($table, $where, 'right');
  968.     }
  969.  
  970.     /**
  971.      * gets the join-condition
  972.      *
  973.      * @return  array   gets the join parameters
  974.      * @access  public
  975.      */
  976.     function getJoin($what=null)
  977.     {
  978.         // if the user requests all the join data or if the join is empty, return it
  979.         if ($what == null || !$this->_join) {
  980.             $ret = $this->_join;
  981.         }
  982.  
  983.         switch(strtolower($what)) {
  984.             case 'table':
  985.             case 'tables':
  986.                 $ret = array();
  987.                 foreach ($this->_join as $aJoin) {
  988.                     if (isset($aJoin['table']) && sizeof($aJoin['table'])) {
  989.                         $ret = array_merge($ret, $aJoin['table']);
  990.                     }
  991.                 }
  992.                 break;
  993.             case 'right':   // return right-join data only
  994.             case 'left':    // return left join data only
  995.                 break;
  996.         }
  997.         return $ret;
  998.     }
  999.  
  1000.     /**
  1001.      * adds a table and a where clause that shall be used for the join
  1002.      * instead of calling
  1003.      *     setJoin(array(table1,table2),'<where clause1> AND <where clause2>')
  1004.      * you can also call
  1005.      *     setJoin(table1,'<where clause1>')
  1006.      *     addJoin(table2,'<where clause2>')
  1007.      * or where it makes more sense is to build a query which is build out of a
  1008.      * left join and a standard join
  1009.      *     setLeftJoin(table1,'<where clause1>')
  1010.      *     // results in ... FROM $this->table LEFT JOIN table ON <where clause1>
  1011.      *     addJoin(table2,'<where clause2>')
  1012.      *     // results in ...  FROM $this->table,table2 LEFT JOIN table ON <where clause1> WHERE <where clause2>
  1013.      *
  1014.      * @param   array   $table
  1015.      * @param   string  $where
  1016.      * @param   string  $type
  1017.      * @access  public
  1018.      */
  1019.     function addJoin($table, $where, $type='default')
  1020.     {
  1021.         settype($table, 'array');
  1022.  
  1023.         // init value, to prevent E_ALL-warning
  1024.         if (!isset($this->_join[$type]) || !$this->_join[$type]) {
  1025.             $this->_join[$type] = array('table'=>array(), 'where'=>'');
  1026.         }
  1027.         $this->_join[$type]['table'] = array_merge($this->_join[$type]['table'], $table);
  1028.         $this->_join[$type]['where'] .= trim($this->_join[$type]['where']) ? ' AND '.$where : $where;
  1029.     }
  1030.  
  1031.     /**
  1032.      * sets the table this class is currently working on
  1033.      *
  1034.      * @param   string  the table name
  1035.      * @access  public
  1036.      */
  1037.     function setTable($table)
  1038.     {
  1039.         $this->table = $table;
  1040.     }
  1041.  
  1042.     /**
  1043.      * gets the table this class is currently working on
  1044.      *
  1045.      * @return  string  the table name
  1046.      * @access  public
  1047.      */
  1048.     function getTable()
  1049.     {
  1050.         return $this->table;
  1051.     }
  1052.  
  1053.     /**
  1054.      * sets the group-by condition
  1055.      *
  1056.      * @param   string  the group condition
  1057.      * @access  public
  1058.      */
  1059.     function setGroup($group='')
  1060.     {
  1061.         $this->_group = $group;
  1062. //FIXXME parse the condition and replace ambigious column names, such as "name='Deutschland'" with "country.name='Deutschland'"
  1063. // then the users dont have to write that explicitly and can use the same name as in the setOrder i.e. setOrder('name,_net_name,_netPrefix_prefix');
  1064.     }
  1065.  
  1066.     /**
  1067.      * gets the group condition which is used for the current instance
  1068.      *
  1069.      * @return  string  the group condition
  1070.      * @access  public
  1071.      */
  1072.     function getGroup()
  1073.     {
  1074.         return $this->_group;
  1075.     }
  1076.  
  1077.     /**
  1078.      * limit the result to return only the columns given in $what
  1079.      * @access public
  1080.      */
  1081.     function setSelect($what='*')
  1082.     {
  1083.         $this->_select = $what;
  1084.     }
  1085.  
  1086.     /**
  1087.      * add a string to the select part of the query
  1088.      *
  1089.      * add a string to the select-part of the query and connects it to an existing
  1090.      * string using the $connectString, which by default is a comma.
  1091.      * (SELECT xxx FROM - xxx is the select-part of a query)
  1092.      *
  1093.      * @param   string  the string that shall be added to the select-part
  1094.      * @param   string  the string to connect the new string with the existing one
  1095.      * @return  void
  1096.      * @access  public
  1097.      */
  1098.     function addSelect($what='*', $connectString=',')
  1099.     {
  1100.         // if the select string is not empty add the string, otherwise simply set it
  1101.         if ($this->_select) {
  1102.             $this->_select = $this->_select . $connectString . $what;
  1103.         } else {
  1104.             $this->_select = $what;
  1105.         }
  1106.     }
  1107.  
  1108.     /**
  1109.      * @access  public
  1110.      */
  1111.     function getSelect()
  1112.     {
  1113.         return $this->_select;
  1114.     }
  1115.  
  1116.     /**
  1117.      * @access  public
  1118.      */
  1119.     function setDontSelect($what='')
  1120.     {
  1121.         $this->_dontSelect = $what;
  1122.     }
  1123.  
  1124.     /**
  1125.      * @access  public
  1126.      */
  1127.     function getDontSelect()
  1128.     {
  1129.         return $this->_dontSelect;
  1130.     }
  1131.  
  1132.     /**
  1133.      * reset all the set* settings, with no parameter given it resets all
  1134.      *
  1135.      * @return  void
  1136.      * @access  public
  1137.      */
  1138.     function reset($what=array())
  1139.     {
  1140.         if (sizeof($what) == 0) {
  1141.             $what = array('select',
  1142.                           'dontSelect',
  1143.                           'group',
  1144.                           'having',
  1145.                           'limit',
  1146.                           'where',
  1147.                           'index',
  1148.                           'order',
  1149.                           'join',
  1150.                           'leftJoin',
  1151.                           'rightJoin');
  1152.         }
  1153.  
  1154.         foreach ($what as $aReset) {
  1155.             $this->{'set'.ucfirst($aReset)}();
  1156.         }
  1157.     }
  1158.  
  1159.     /**
  1160.      * set mode the class shall work in
  1161.      * currently we have the modes:
  1162.      * 'raw'   does not quote the data before building the query
  1163.      *
  1164.      * @param   string   the mode to be set
  1165.      * @param   mixed    the value of the mode
  1166.      * @return  void
  1167.      * @access  public
  1168.      */
  1169.     function setOption($option, $value)
  1170.     {
  1171.         $this->options[strtolower($option)] = $value;
  1172.     }
  1173.  
  1174.     /**
  1175.      * @param   string name of the option to retrieve
  1176.      * @access  public
  1177.      */
  1178.     function getOption($option)
  1179.     {
  1180.         return $this->options[strtolower($option)];
  1181.     }
  1182.  
  1183.     /**
  1184.      * quotes all the data in this array if we are not in raw mode!
  1185.      * @access private
  1186.      */
  1187.     function _quoteArray($data)
  1188.     {
  1189.         if (!$this->getOption('raw')) { //check added for gain in speed if $this->raw==true
  1190.             foreach ($data as $key => $val) {
  1191.                 $data[$key] = $this->_quote($val);
  1192.             }
  1193.         }
  1194.         return $data;
  1195.     }
  1196.  
  1197.     /**
  1198.      * quotes all the data in this array if we are not in raw mode!
  1199.      * @access private
  1200.      */
  1201.     function _quote($data)
  1202.     {
  1203.         if (!$this->getOption('raw')) {
  1204.             switch(gettype($data)) {
  1205.                 case 'array':   return $this->_quoteArray($data);
  1206.                                 break;
  1207.                 case 'boolean': return $this->db->getBooleanValue($data);
  1208.                                 break;
  1209.                 case 'double':  return $this->db->getFloatValue($data);
  1210.                                 break;
  1211.                 case 'integer': return $this->db->getIntegerValue($data);
  1212.                                 break;
  1213.                 case 'string':  //if 'string' or 'unknown', quote as text
  1214.                 default:        return $this->db->getTextValue($data);
  1215.             }
  1216.         }
  1217.     }
  1218.  
  1219.     /**
  1220.      * checks if the columns which are given as the array's indexes really exist
  1221.      * if not it will be unset anyway
  1222.      *
  1223.      * @access  public
  1224.      * @param   string  the actual message, first word should always be the method name,
  1225.      *                  to build the message like this: className::methodname
  1226.      * @param   integer the line number
  1227.      */
  1228.     function _checkColumns($newData, $method='unknown')
  1229.     {
  1230.         if (!$meta = $this->metadata()) {
  1231.             // if no metadata available, return data as given
  1232.             return $newData;
  1233.         }
  1234.         foreach ($newData as $colName => $x) {
  1235.             if (!isset($meta[$colName])) {
  1236.                 $this->_errorLog("$method, column {$this->table}.$colName doesnt exist, value was removed before '$method'",__LINE__);
  1237.                 unset($newData[$colName]);
  1238.             } else {
  1239.                 // if the current column exists, check the length too, not to write content that is too long
  1240.                 // prevent DB-errors here
  1241.                 // do only check the data length if this field is given
  1242. // FIXXME use PEAR-defined field for 'DATA_LENGTH'
  1243.                 if (isset($meta[$colName]['DATA_LENGTH']) &&
  1244.                     ($oldLength=strlen($newData[$colName])) > $meta[$colName]['DATA_LENGTH'])
  1245.                 {
  1246.                     $this->_errorLog("_checkColumns, had to trim column '$colName' from $oldLength to ".
  1247.                                         $meta[$colName]['DATA_LENGTH'].' characters.',__LINE__);
  1248.                     $newData[$colName] = substr($newData[$colName],0,$meta[$colName]['DATA_LENGTH']);
  1249.                 }
  1250.             }
  1251.         }
  1252.         return $newData;
  1253.     }
  1254.  
  1255.     /**
  1256.      * overwrite this method and i.e. print the query $string
  1257.      * to see the final query
  1258.      *
  1259.      * @param string  the query mostly
  1260.      * @access public
  1261.      */
  1262.     function debug($string) {}
  1263.  
  1264.     //
  1265.     //
  1266.     //  ONLY ORACLE SPECIFIC, not very nice since it is DB dependent, but we need it!!!
  1267.     //
  1268.     //
  1269.  
  1270.     /**
  1271.      * !!!! query COPIED FROM db_oci8.inc - from PHPLIB !!!!
  1272.      *
  1273.      * @see db_oci8.inc - PHPLIB
  1274.      * @param string $table
  1275.      * @return resultSet or false on error
  1276.      * @access public
  1277.      */
  1278.     function metadata($table='')
  1279.     {
  1280.         // is there an alias in the table name, then we have something like this: 'user ua'
  1281.         // cut of the alias and return the table name
  1282.         if (strpos($table, ' ') !== false) {
  1283.             $split = explode(' ', trim($table));
  1284.             $table = $split[0];
  1285.         }
  1286.  
  1287.         $full = false;
  1288.         if (empty($table)) {
  1289.             $table = $this->table;
  1290.         }
  1291.         // to prevent multiple selects for the same metadata
  1292.         if (isset($this->_metadata[$table])) {
  1293.             return $this->_metadata[$table];
  1294.         }
  1295. // FIXXXME use oci8 implementation of newer PEAR::DB-version
  1296.         if ($this->db->phptype=='oci8') {
  1297.             $count = 0;
  1298.             $id    = 0;
  1299.             $res   = array();
  1300.  
  1301.             //# This is a RIGHT OUTER JOIN: "(+)", if you want to see, what
  1302.             //# this query results try the following:
  1303.             //// $table = new Table; $this->db = new my_DB_Sql; // you have to make
  1304.             ////                                          // your own class
  1305.             //// $table->show_results($this->db->query(see query vvvvvv))
  1306.             ////
  1307.             $res = $this->db->getAll("SELECT T.column_name,T.table_name,T.data_type,".
  1308.                 "T.data_length,T.data_precision,T.data_scale,T.nullable,".
  1309.                 "T.char_col_decl_length,I.index_name".
  1310.                 " FROM ALL_TAB_COLUMNS T,ALL_IND_COLUMNS I".
  1311.                 " WHERE T.column_name=I.column_name (+)".
  1312.                 " AND T.table_name=I.table_name (+)".
  1313.                 " AND T.table_name=UPPER('$table') ORDER BY T.column_id");
  1314.  
  1315.             if (MDB::isError($res)) {
  1316.                 //$this->_errorSet( $res->getMessage() );
  1317.                 // i think we only need to log here, since this method is never used
  1318.                 // directly for the user's functionality, which means if it fails it
  1319.                 // is most probably an appl error
  1320.                 $this->_errorLog($this->db->getUserInfo($res));
  1321.                 return false;
  1322.             }
  1323.             foreach ($res as $key=>$val) {
  1324.                 $res[$key]['name'] = $val['COLUMN_NAME'];
  1325.             }
  1326.         } else {
  1327.             $res = $this->db->tableinfo($table);
  1328.             if (MDB::isError($res)) {
  1329.                 $this->_errorSet($res->getUserInfo());
  1330.                 return false;
  1331.             }
  1332.         }
  1333.  
  1334.         $ret = array();
  1335.         foreach ($res as $key => $val) {
  1336.             $ret[$val['name']] = $val;
  1337.         }
  1338.         $this->_metadata[$table] = $ret;
  1339.         return $ret;
  1340.     }
  1341.  
  1342.     //
  1343.     //  methods for building the query
  1344.     //
  1345.  
  1346.     /**
  1347.      * build the from string
  1348.      *
  1349.      * @return  string  the string added behind FROM
  1350.      * @access  public
  1351.      */
  1352.     function _buildFrom()
  1353.     {
  1354.         $from = $this->table;
  1355.  
  1356.         if ($join = $this->getJoin()) {  // is join set?
  1357.             // handle the standard join thingy
  1358.             if (@$join['default']) {
  1359.                 $from .= ','.implode(',', $join['default']['table']);
  1360.             }
  1361.  
  1362.             // if we also have a left join, add the 'LEFT JOIN table ON condition'
  1363.             $joinType = !empty($join['left']) ? 'left' : (!empty($join['right']) ? 'right' : false);
  1364. // this class can only handle one kind of join at a time ... how stupid :-)
  1365.             if ($joinType) {
  1366.                 // do we have any of the above checked join-types?
  1367.                 $joinExpr = ' '.strtoupper($joinType).' JOIN ';
  1368.                 $tables = $join[$joinType]['table'];
  1369.                 settype($tables,'array');
  1370.                 $wheres = $join[$joinType]['where'];
  1371.                 settype($wheres, 'array');
  1372.                 foreach ($wheres as $k => $where) {
  1373.                     $from .= $joinExpr . $tables[$k];
  1374.                     // replace the _TABLENAME_COLUMNNAME by TABLENAME.COLUMNNAME
  1375.                     // since oracle doesnt work with the _TABLENAME_COLUMNNAME which i think is strange
  1376. // FIXXME i think this should become deprecated since the setWhere should not be used like this: '_table_column' but 'table.column'
  1377.                     $regExp = '/_('.implode('|', $join[$joinType]['table']).')_([^\s]+)/';
  1378.                     $where = preg_replace($regExp, '$1.$2', $where);
  1379.  
  1380.                     // add the table name before any column that has no table prefix
  1381.                     // since this might cause "unambigious column" errors
  1382.                     if ($meta = $this->metadata())
  1383.                         foreach ($meta as $aCol => $x) {
  1384.                             // this covers the LIKE,IN stuff: 'name LIKE "%you%"'  'id IN (2,3,4,5)'
  1385.                             $where = preg_replace('/\s'.$aCol.'\s/', " {$this->table}.$aCol ", $where);
  1386.                             // replace also the column names which are behind a '='
  1387.                             // and do this also if the aCol is at the end of the where clause
  1388.                             // that's what the $ is for
  1389.                             $where = preg_replace('/=\s*'.$aCol.'(\s|$)/', "={$this->table}.$aCol ", $where );
  1390.                             // replace if colName is first and possibly also if at the beginning of the where-string
  1391.                             $where = preg_replace('/(^\s*|\s+)'.$aCol.'\s*=/', "$1{$this->table}.$aCol=", $where );
  1392.                         }
  1393.  
  1394.                         $from .= ' ON '.$where;
  1395.                     }
  1396.                 }
  1397.             }
  1398.         return $from;
  1399.     }
  1400.  
  1401.     /**
  1402.      * this method gets the short name for a table
  1403.      *
  1404.      * get the short name for a table, this is needed to properly build the
  1405.      * 'AS' parts in the select query
  1406.      * @param  string  the real table name
  1407.      * @return string  the table's short name
  1408.      * @access public
  1409.      */
  1410.     function getTableShortName($table)
  1411.     {
  1412.         $tableSpec = $this->getTableSpec(false);
  1413.         if (isset($tableSpec[$table]['shortName']) && $tableSpec[$table]['shortName']) {
  1414. //print "$table ... ".$tableSpec[$table]['shortName'].'<br />';
  1415.             return $tableSpec[$table]['shortName'];
  1416.         }
  1417.  
  1418.         $possibleTableShortName = preg_replace($this->_tableNameToShortNamePreg, '', $table);
  1419. //print "$table ... $possibleTableShortName<br />";
  1420.         return $possibleTableShortName;
  1421.     }
  1422.  
  1423.     /**
  1424.      * gets the tableSpec either indexed by the short name or the name
  1425.      * returns the array for the tables given as parameter or if no
  1426.      * parameter given for all tables that exist in the tableSpec
  1427.      *
  1428.      * @param   array   table names (not the short names!)
  1429.      * @param   boolean if true the table is returned indexed by the shortName
  1430.      *                  otherwise indexed by the name
  1431.      * @return  array   the tableSpec indexed
  1432.      * @access public
  1433.      */
  1434.     function getTableSpec($shortNameIndexed=true, $tables=array())
  1435.     {
  1436.         $newSpec = array();
  1437.         foreach ($this->tableSpec as $aSpec) {
  1438.             if (sizeof($tables)==0 || in_array($aSpec['name'], $tables)) {
  1439.                 if ($shortNameIndexed) {
  1440.                     $newSpec[$aSpec['shortName']] = $aSpec;
  1441.                 } else {
  1442.                     $newSpec[$aSpec['name']] = $aSpec;
  1443.                 }
  1444.             }
  1445.         }
  1446.         return $newSpec;
  1447.     }
  1448.  
  1449.     /**
  1450.      * build the 'SELECT <what> FROM ... 'for a select
  1451.      *
  1452.      * @param   string  if given use this string
  1453.      * @return  string  the what-clause
  1454.      * @access  private
  1455.      */
  1456.     function _buildSelect($what=null)
  1457.     {
  1458.         // what has preference, that means if what is set it is used
  1459.         // this is only because the methods like 'get' pass an individually built value, which
  1460.         // is supposed to be used, but usually it's generically build using the 'getSelect' values
  1461.         if (!$what && $this->getSelect()) {
  1462.             $what = $this->getSelect();
  1463.         }
  1464.  
  1465.         //
  1466.         // replace all the '*' by the real column names, and take care of the dontSelect-columns!
  1467.         //
  1468.         $dontSelect = $this->getDontSelect();
  1469.         $dontSelect = $dontSelect ? explode(',', $dontSelect) : array(); // make sure dontSelect is an array
  1470.  
  1471.         // here we will replace all the '*' and 'table.*' by all the columns that this table
  1472.         // contains. we do this so we can easily apply the 'dontSelect' values.
  1473.         // and so we can also handle queries like: 'SELECT *,count() FROM ' and 'SELECT table.*,x FROM ' too
  1474.         if (strpos($what, '*') !== false) {
  1475.             // subpattern 1 get all the table names, that are written like this: 'table.*' including '*'
  1476.             // for '*' the tablename will be ''
  1477.             preg_match_all('/([^,]*)(\.)?\*\s*(,|$)/U', $what, $res);
  1478. //print "$what ... "; print_r($res); print '<br />';
  1479.             $selectAllFromTables = array_unique($res[1]); // make the table names unique, so we do it all just once for each table
  1480.             $tables = array();
  1481.             if (in_array('', $selectAllFromTables)) { // was there a '*' ?
  1482.                 // get all the tables that we need to process, depending on if joined or not
  1483.                 $tables = $this->getJoin() ?
  1484.                                 array_merge($this->getJoin('tables'), array($this->table)) : // get the joined tables and this->table
  1485.                                 array($this->table);        // create an array with only this->table
  1486.             } else {
  1487.                 $tables = $selectAllFromTables;
  1488.             }
  1489.  
  1490.             $cols = array();
  1491.             foreach ($tables as $aTable) {      // go thru all the tables and get all columns for each, and handle 'dontSelect'
  1492.                 if ($meta = $this->metadata($aTable)) {
  1493.                     foreach ($meta as $colName => $x) {
  1494.                         // handle the dontSelect's
  1495.                         if (in_array($colName, $dontSelect) || in_array("$aTable.$colName", $dontSelect)) {
  1496.                             continue;
  1497.                         }
  1498.  
  1499.                         // build the AS clauses
  1500.                         // put " around them to enable use of reserved words, i.e. SELECT table.option as option FROM...
  1501.                         // and 'option' actually is a reserved word, at least in mysql
  1502.                         // put double quotes around them, since pgsql doesnt work with single quotes
  1503.                         if ($aTable == $this->table) {
  1504.                             $cols[$aTable][] = $this->table. '.' .$colName . ' AS "'. $colName .'"';
  1505.                         } else {
  1506.                             //$cols[$aTable][] = "$aTable.$colName AS \"_".$this->getTableShortName($aTable)."_$colName\"";
  1507.                             $cols[$aTable][] = $aTable. '.' .$colName .' AS "_'. $this->getTableShortName($aTable) .'_'. $colName .'"';
  1508.                         }
  1509.                     }
  1510.                 }
  1511.             }
  1512.  
  1513.             // put the extracted select back in the $what
  1514.             // that means replace 'table.*' by the i.e. 'table.id AS _table_id'
  1515.             // or if it is the table of this class replace 'table.id AS id'
  1516.             if (in_array('', $selectAllFromTables)) {
  1517.                 $allCols = array();
  1518.                 foreach ($cols as $aTable) {
  1519.                     $allCols[] = implode(',', $aTable);
  1520.                 }
  1521.                 $what = preg_replace('/(^|,)\*($|,)/', '$1'.implode(',', $allCols).'$2', $what);
  1522.                 // remove all the 'table.*' since we have selected all anyway (because there was a '*' in the select)
  1523.                 $what = preg_replace('/[^,]*(\.)?\*\s*(,|$)/U', '', $what);
  1524.             } else {
  1525.                 foreach ($cols as $tableName => $aTable) {
  1526.                     if (is_array($aTable) && sizeof($aTable)) {
  1527.                         // replace all the 'table.*' by their select of each column
  1528.                         $what = preg_replace('/(^|,)\s*'.$tableName.'\.\*\s*($|,)/', '$1'.implode(',', $aTable).'$2', $what);
  1529.                     }
  1530.                 }
  1531.             }
  1532.         }
  1533.  
  1534.         if ($this->getJoin()) {
  1535.             // replace all 'column' by '$this->table.column' to prevent ambigious errors
  1536.             $metadata = $this->metadata();
  1537.             if (is_array($metadata)) {
  1538.                 foreach ($this->metadata() as $aCol => $x) {
  1539.                     // handle ',id as xid,MAX(id),id' etc.
  1540. // FIXXME do this better!!!
  1541.                     $what = preg_replace(   "/(^|,|\()(\s*)$aCol(\)|\s|,|as|$)/i",
  1542.                                             // $2 is actually just to keep the spaces, is not really
  1543.                                             // necessary, but this way the test works independent of this functionality here
  1544.                                             "$1$2{$this->table}.$aCol$3",
  1545.                                             $what);
  1546.                 }
  1547.             }
  1548.             // replace all 'joinedTable.columnName' by '_joinedTable_columnName'
  1549.             // this actually only has an effect if there was no 'table.*' for 'table'
  1550.             // if that was there, then it has already been done before
  1551.             foreach ($this->getJoin('tables') as $aTable) {
  1552.                 if ($meta = $this->metadata($aTable)) {
  1553.                     foreach ($meta as $aCol => $x) {
  1554.                         // dont put the 'AS' behind it if there is already one
  1555.                         if (preg_match("/$aTable.$aCol\s*as/i", $what)) {
  1556.                             continue;
  1557.                         }
  1558.                         // this covers a ' table.colName ' surrounded by spaces, and replaces it by ' table.colName AS _table_colName'
  1559.                         $what = preg_replace('/\s'.$aTable.'.'.$aCol.'\s/', " $aTable.$aCol AS _".$this->getTableShortName($aTable)."_$aCol ", $what);
  1560.                         // replace also the column names which are behind a ','
  1561.                         // and do this also if the aCol is at the end that's what the $ is for
  1562.                         $what = preg_replace('/,\s*'.$aTable.'.'.$aCol.'(,|\s|$)/', ",$aTable.$aCol AS _".$this->getTableShortName($aTable)."_$aCol$1", $what);
  1563.                         // replace if colName is first and possibly also if at the beginning of the where-string
  1564.                         $what = preg_replace('/(^\s*|\s+)'.$aTable.'.'.$aCol.'\s*,/', "$1$aTable.$aCol AS _".$this->getTableShortName($aTable)."_$aCol,", $what);
  1565.                     }
  1566.                 }
  1567.             }
  1568.         }
  1569.         return $what;
  1570.     }
  1571.  
  1572.     /**
  1573.      *
  1574.      * @param  string $where WHERE clause
  1575.      * @return string $where WHERE clause after processing
  1576.      * @access private
  1577.      */
  1578.     function _buildWhere($where='')
  1579.     {
  1580.         if ($this->getWhere()) {
  1581.             if ($where) {
  1582.                 $where = $this->getWhere().' AND '.$where;
  1583.             } else {
  1584.                 $where = $this->getWhere();
  1585.             }
  1586.         }
  1587.  
  1588.         if ($join = $this->getJoin())   // is join set?
  1589.         {
  1590.             // only those where conditions in the default-join have to be added here
  1591.             // left-join conditions are added behind 'ON', the '_buildJoin()' does that
  1592.             if (@strlen($join['default']['where']) > 0) {
  1593.                 // we have to add this join-where clause here
  1594.                 // since at least in mysql a query like: select * from tableX JOIN tableY ON ...
  1595.                 // doesnt work, may be that's even SQL-standard...
  1596.                 if (trim($where)) {
  1597.                     $where = $join['default']['where'].' AND '.$where;
  1598.                 } else {
  1599.                     $where = $join['default']['where'];
  1600.                 }
  1601.             }
  1602.             // replace the _TABLENAME_COLUMNNAME by TABLENAME.COLUMNNAME
  1603.             // since oracle doesnt work with the _TABLENAME_COLUMNNAME which i think is strange
  1604. // FIXXME i think this should become deprecated since the setWhere should not be used like this: '_table_column' but 'table.column'
  1605.             $regExp = '/_('.implode('|', $this->getJoin('tables')).')_([^\s]+)/';
  1606.             $where = preg_replace( $regExp , '$1.$2' , $where );
  1607.             // add the table name before any column that has no table prefix
  1608.             // since this might cause "unambigious column" errors
  1609.             if ($meta = $this->metadata()) {
  1610.                 foreach ($meta as $aCol=>$x) {
  1611.                     // this covers the LIKE,IN stuff: 'name LIKE "%you%"'  'id IN (2,3,4,5)'
  1612.                     $where = preg_replace('/\s'.$aCol.'\s/' , " {$this->table}.$aCol ", $where );
  1613.                     // replace also the column names which are behind a '='
  1614.                     // and do this also if the aCol is at the end of the where clause
  1615.                     // that's what the $ is for
  1616.                     $where = preg_replace('/([=<>])\s*'.$aCol.'(\s|$)/', "$1{$this->table}.$aCol ", $where );
  1617.                     // replace if colName is first and possibly also if at the beginning of the where-string
  1618.                     $where = preg_replace('/(^\s*|\s+)'.$aCol.'\s*([=<>])/', "$1{$this->table}.$aCol$2", $where );
  1619.                 }
  1620.             }
  1621.         }
  1622.         return $where;
  1623.     }
  1624.  
  1625.     /**
  1626.      *
  1627.      * @return string $order
  1628.      * @access private
  1629.      */
  1630.     function _buildOrder()
  1631.     {
  1632.         $order = $this->getOrder();
  1633.         // replace 'column' by '$this->table.column' if the column is defined for $this->table
  1634.         if ($meta = $this->metadata()) {
  1635.             foreach ($meta as $aCol=>$x) {
  1636.                 $order = preg_replace('/(^\s*|\s+|,)'.$aCol.'\s*(,)?/U', "$1{$this->table}.$aCol$2", $order);
  1637.             }
  1638.         }
  1639.         return $order;
  1640.     }
  1641.  
  1642.  
  1643.     /**
  1644.      * Build the group-clause, replace 'column' by 'table.column'.
  1645.      *
  1646.      * @return string the rendered group clause
  1647.      * @access private
  1648.      */
  1649.     function _buildGroup()
  1650.     {
  1651.         $group = $this->getGroup();
  1652.         // replace 'column' by '$this->table.column' if the column is defined for $this->table
  1653.         if ($meta = $this->metadata()) {
  1654.             foreach ($meta as $aCol=>$x) {
  1655.                 $group = preg_replace('/(^\s*|\s+|,)'.$aCol.'\s*(,)?/U', "$1{$this->table}.$aCol$2", $group);
  1656.             }
  1657.         }
  1658.         return $group;
  1659.     }
  1660.  
  1661.     /**
  1662.      *
  1663.      *
  1664.      * @return string the having clause
  1665.      * @access private
  1666.      */
  1667.     function _buildHaving()
  1668.     {
  1669.         $having = $this->getHaving();
  1670.         // replace 'column' by '$this->table.column' if the column is defined for $this->table
  1671.         if ($meta = $this->metadata()) {
  1672.             foreach ($meta as $aCol=>$x) {
  1673.                 $having = preg_replace('/(^\s*|\s+|,)'.$aCol.'\s*(,)?/U', "$1{$this->table}.$aCol$2", $having);
  1674.             }
  1675.         }
  1676.         return $having;
  1677.     }
  1678.  
  1679.     /**
  1680.      *
  1681.      * @param  array   this array contains the elements of the query,
  1682.      *                 indexed by their key, which are: 'select','from','where', etc.
  1683.      * @return string $querystring or false on error
  1684.      * @access private
  1685.      */
  1686.     function _buildSelectQuery($query=array())
  1687.     {
  1688.         $where = isset($query['where']) ? $query['where'] : $this->_buildWhere();
  1689.         if ($where) {
  1690.             $where = 'WHERE '.$where;
  1691.         }
  1692.         $order = isset($query['order']) ? $query['order'] : $this->_buildOrder();
  1693.         if ($order) {
  1694.             $order = 'ORDER BY '.$order;
  1695.         }
  1696.         $group = isset($query['group']) ? $query['group'] : $this->_buildGroup();
  1697.         if ($group) {
  1698.             $group = 'GROUP BY '.$group;
  1699.         }
  1700.         $having = isset($query['having']) ? $query['having'] : $this->_buildHaving();
  1701.         if ($having) {
  1702.             $having = 'HAVING '.$having;
  1703.         }
  1704.         $queryString = sprintf( 'SELECT %s FROM %s %s %s %s %s',
  1705.                                 isset($query['select']) ? $query['select'] : $this->_buildSelect(),
  1706.                                 isset($query['from'])   ? $query['from']   : $this->_buildFrom(),
  1707.                                 $where,
  1708.                                 $group,
  1709.                                 $order,
  1710.                                 $having
  1711.                                 );
  1712.         // $query['limit'] has preference!
  1713.         $limit = isset($query['limit']) ? $query['limit'] : $this->_limit;
  1714.         if (@$limit[1]) {    // is there a count set?
  1715.             if (MDB::isError($error = $this->db->setSelectedRowRange($limit[0], $limit[1]))) {
  1716.                 $this->_errorSet('MDB_QueryTool_Common::_buildSelectQuery setSelectedRowRange failed '.$error->getMessage());
  1717.                 $this->_errorLog($error->getUserInfo());
  1718.                 return false;
  1719.             }
  1720.             /*
  1721.             $queryString = $this->db->modifyLimitQuery($queryString, $limit[0], $limit[1]);
  1722.             if (DB::isError($queryString)) {
  1723.                 $this->_errorSet('DB_QueryTool::db::modifyLimitQuery failed '.$queryString->getMessage());
  1724.                 $this->_errorLog($queryString->getUserInfo());
  1725.                 return false;
  1726.             }
  1727.             */
  1728.         }
  1729.         return $queryString;
  1730.     }
  1731.  
  1732.     /**
  1733.      * this simply builds an update query.
  1734.      *
  1735.      * @param  array   the parameter array might contain the following indexes
  1736.      *         'where'   the where clause to be added, i.e.
  1737.      *                   UPDATE table SET x=1 WHERE y=0
  1738.      *                   here the 'where' part simply would be 'y=0'
  1739.      *         'set'     the actual data to be updated
  1740.      *                   in the example above, that would be 'x=1'
  1741.      * @return string the resulting query
  1742.      * @access private
  1743.      */
  1744.     function _buildUpdateQuery($query=array())
  1745.     {
  1746.         $where = isset($query['where']) ? $query['where'] : $this->_buildWhere();
  1747.         if ($where) {
  1748.             $where = 'WHERE '.$where;
  1749.         }
  1750.  
  1751.         $updateString = sprintf('UPDATE %s SET %s %s',
  1752.                                 $this->table,
  1753.                                 $query['set'],
  1754.                                 $where
  1755.                             );
  1756.         return $updateString;
  1757.     }
  1758.  
  1759.     /**
  1760.      *
  1761.      * @param string $query
  1762.      * @param string method
  1763.      * @return resultSet or false on error
  1764.      * @access public
  1765.      */
  1766.     function execute($query=null, $method='getAll')
  1767.     {
  1768.         $this->writeLog();
  1769.         if (is_null($query)) {
  1770.             $query = $this->_buildSelectQuery();
  1771.         }
  1772.         $this->writeLog('query built: '.$query);
  1773. // FIXXME on ORACLE this doesnt work, since we return joined columns as _TABLE_COLNAME and the _ in front
  1774. // doesnt work on oracle, add a letter before it!!!
  1775.         $this->_lastQuery = $query;
  1776.  
  1777.         $this->debug($query);
  1778.         $this->writeLog('start query');
  1779.         if (MDB::isError($res = $this->db->$method($query))) {
  1780.             if ($this->getOption('verbose')) {
  1781.                 //$this->_errorSet($this->db->errorMessage($res->getCode()));
  1782.                 $this->_errorSet($res->getMessage() .'-'. $res->getUserInfo());
  1783.             } else {
  1784.                 //$this->_errorLog($this->db->errorMessage($res->getCode()));
  1785.                 $this->_errorLog($res->getMessage());
  1786.             }
  1787.             $this->_errorLog($res->getUserInfo(), __LINE__);
  1788.             return false;
  1789.         } else {
  1790.             $this->writeLog('end query');
  1791.         }
  1792.  
  1793.         return $this->_makeIndexed($res);
  1794.     }
  1795.  
  1796.     /**
  1797.      * Write events to the logfile.
  1798.      *
  1799.      * It does some additional work, like time measuring etc. to
  1800.      * see some additional info
  1801.      *
  1802.      * @param string $text
  1803.      * @access public
  1804.      */
  1805.     function writeLog($text='START')
  1806.     {
  1807. //its still really a quicky.... 'refactor' (nice word) that
  1808.         if (!isset($this->options['logfile'])) {
  1809.             return;
  1810.         }
  1811.  
  1812.         include_once 'Log.php';
  1813.         if (!class_exists('Log')) {
  1814.             return;
  1815.         }
  1816.         if (!$this->_logObject) {
  1817.             $this->_logObject =& Log::factory('file', $this->options['logfile']);
  1818.         }
  1819.  
  1820.         if ($text == 'start query' || $text === 'end query') {
  1821.             $bytesSent = $this->db->getAll("SHOW STATUS like 'Bytes_sent'");
  1822.             $bytesSent = $bytesSent[0]['Value'];
  1823.         }
  1824.         if ($text === 'START') {
  1825.             $startTime = split(" ", microtime());
  1826.             $this->_logData['startTime'] = $startTime[1] + $startTime[0];
  1827.         }
  1828.         if ($text === 'start query') {
  1829.             $this->_logData['startBytesSent'] = $bytesSent;
  1830.             $startTime = split(" ", microtime());
  1831.             $this->_logData['startQueryTime'] = $startTime[1] + $startTime[0];
  1832.             return;
  1833.         }
  1834.         if ($text === 'end query') {
  1835.             $text .= ' result size: '.((int)$bytesSent-(int)$this->_logData['startBytesSent']).' bytes';
  1836.             $endTime = split(" ", microtime());
  1837.             $endTime = $endTime[1] + $endTime[0];
  1838.             $text .= ', took: '.(($endTime - $this->_logData['startQueryTime'])).' seconds';
  1839.         }
  1840.         if (strpos($text, 'query built') === 0) {
  1841.             $endTime = split(" ", microtime());
  1842.             $endTime = $endTime[1] + $endTime[0];
  1843.             $this->writeLog('query building took: '.(($endTime - $this->_logData['startTime'])).' seconds');
  1844.         }
  1845.         $this->_logObject->log($text);
  1846.  
  1847.         if (strpos($text, 'end query') === 0) {
  1848.             $endTime = split(' ', microtime());
  1849.             $endTime = $endTime[1] + $endTime[0];
  1850.             $text = 'time over all: '.(($endTime - $this->_logData['startTime'])).' seconds';
  1851.             $this->_logObject->log($text);
  1852.         }
  1853.     }
  1854.  
  1855.     /**
  1856.      *
  1857.      *
  1858.      * @param  resultSet reference
  1859.      * @return MDB_QueryTool_Result if "useResult"==TRUE, the $result otherwise
  1860.      * @access public
  1861.      */
  1862.     function returnResult(&$result)
  1863.     {
  1864.         if ($this->_useResult) {
  1865.             if ($result === false) {
  1866.                 return false;
  1867.             }
  1868.             return new MDB_QueryTool_Result($result);
  1869.         }
  1870.         return $result;
  1871.     }
  1872.  
  1873.     /**
  1874.      *
  1875.      * @param  mixed $data
  1876.      * @return mixed $data or array $indexedData
  1877.      * @access public
  1878.      */
  1879.     function &_makeIndexed(&$data)
  1880.     {
  1881.         // we can only return an indexed result if the result has a number of columns
  1882.         if (is_array($data) && sizeof($data) && $key=$this->getIndex()) {
  1883.             // build the string to evaluate which might be made up out of multiple indexes of a result-row
  1884.             $evalString = '$val[\''.implode('\'].\',\'.$val[\'',explode(',',$key)).'\']';   //"
  1885.  
  1886.             $indexedData = array();
  1887. //FIXXME actually we also need to check ONCE if $val is an array, so to say if $data is 2-dimensional
  1888.             foreach ($data as $val) {
  1889.                 eval("\$keyValue = $evalString;");  // get the actual real (string-)key (string if multiple cols are used as index)
  1890.                 $indexedData[$keyValue] = $val;
  1891.             }
  1892.             unset($data);
  1893.             return $indexedData;
  1894.         }
  1895.         return $data;
  1896.     }
  1897.  
  1898.  
  1899.     /**
  1900.      * format the result to be indexed by $key
  1901.      * NOTE: be careful, when using this you should be aware, that if you
  1902.      * use an index which's value appears multiple times you may loose data
  1903.      * since a key cant exist multiple times!!
  1904.      * the result for a result to be indexed by a key(=columnName)
  1905.      * (i.e. 'relationtoMe') which's values are 'brother' and 'sister'
  1906.      * or alike normally returns this:
  1907.      *     $res['brother'] = array('name'=>'xxx')
  1908.      *     $res['sister'] = array('name'=>'xxx')
  1909.      * but if the column 'relationtoMe' contains multiple entries for 'brother'
  1910.      * then the returned dataset will only contain one brother, since the
  1911.      * value from the column 'relationtoMe' is used
  1912.      * and which 'brother' you get depends on a lot of things, like the sortorder,
  1913.      * how the db saves the data, and whatever else
  1914.      *
  1915.      * you can also set indexes which depend on 2 columns, simply pass the parameters like
  1916.      * 'table1.id,table2.id' it will be used as a string for indexing the result
  1917.      * and the index will be built using the 2 values given, so a possible
  1918.      * index might be '1,2' or '2108,29389' this way you can access data which
  1919.      * have 2 primary keys. Be sure to remember that the index is a string!
  1920.      *
  1921.      * @param  string $key
  1922.      * @access public
  1923.      */
  1924.     function setIndex($key=null)
  1925.     {
  1926.         if ($this->getJoin()) {  // is join set?
  1927.  
  1928.             // replace TABLENAME.COLUMNNAME by _TABLENAME_COLUMNNAME
  1929.             // since this is only the result-keys can be used for indexing :-)
  1930.             $regExp = '/('.implode('|',$this->getJoin('tables')).')\.([^\s]+)/';
  1931.             $key = preg_replace($regExp, '_$1_$2', $key);
  1932.  
  1933.             // remove the table name if it is in front of '<$this->table>.columnname'
  1934.             // since the key doesnt contain it neither
  1935.             if ($meta = $this->metadata()) {
  1936.                 foreach ($meta as $aCol => $x) {
  1937.                     $key = preg_replace('/'.$this->table.'\.'.$aCol.'/', $aCol, $key);
  1938.                 }
  1939.             }
  1940.         }
  1941.         $this->_index = $key;
  1942.     }
  1943.  
  1944.     /**
  1945.      *
  1946.      * @return string index
  1947.      * @access public
  1948.      */
  1949.     function getIndex()
  1950.     {
  1951.         return $this->_index;
  1952.     }
  1953.  
  1954.     /**
  1955.      *
  1956.      * @param  boolean
  1957.      * @access public
  1958.      */
  1959.     function useResult($doit=true)
  1960.     {
  1961.         $this->_useResult = $doit;
  1962.         if ($doit) {
  1963.             require_once 'MDB/QueryTool/Result.php';
  1964.         }
  1965.     }
  1966.  
  1967.     /**
  1968.      * set both callbacks
  1969.      * @access public
  1970.      */
  1971.     function setErrorCallback($param='')
  1972.     {
  1973.         $this->setErrorLogCallback($param);
  1974.         $this->setErrorSetCallback($param);
  1975.     }
  1976.  
  1977.     function setErrorLogCallback($param='')
  1978.     {
  1979.         $errorLogCallback = &PEAR::getStaticProperty('MDB_QueryTool', '_errorLogCallback');
  1980.         $errorLogCallback = $param;
  1981.     }
  1982.  
  1983.     function setErrorSetCallback($param='')
  1984.     {
  1985.         $errorSetCallback = &PEAR::getStaticProperty('MDB_QueryTool', '_errorSetCallback');
  1986.         $errorSetCallback = $param;
  1987.     }
  1988.  
  1989.     /**
  1990.      * sets error log and adds additional info
  1991.      *
  1992.      * @param  string  the actual message, first word should always be the method name,
  1993.      *                 to build the message like this: className::methodname
  1994.      * @param  integer the line number
  1995.      * @access private
  1996.      */
  1997.     function _errorLog($msg, $line='unknown')
  1998.     {
  1999.         $this->_errorHandler('log', $msg, $line);
  2000. /*
  2001.         if ($this->getOption('verbose') == true) {
  2002.             $this->_errorLog( get_class($this)."::$msg ($line)");
  2003.             return;
  2004.         }
  2005.         if ($this->_errorLogCallback) {
  2006.             call_user_func( $this->_errorLogCallback , $msg );
  2007.         }
  2008. */
  2009.     }
  2010.  
  2011.     function _errorSet($msg, $line='unknown')
  2012.     {
  2013.         $this->_errorHandler('set', $msg, $line);
  2014.     }
  2015.  
  2016.     function _errorHandler($logOrSet, $msg, $line='unknown')
  2017.     {
  2018. /* what did i do this for?
  2019.         if ($this->getOption('verbose') == true) {
  2020.             $this->_errorHandler($logOrSet, get_class($this)."::$msg ($line)");
  2021.             return;
  2022.         }
  2023. */
  2024.  
  2025.         $msg = get_class($this)."::$msg ($line)";
  2026.  
  2027.         $logOrSet = ucfirst($logOrSet);
  2028.         $callback = &PEAR::getStaticProperty('MDB_QueryTool', '_error' . $logOrSet . 'Callback');
  2029.         if ($callback) {
  2030.             call_user_func($callback, $msg);
  2031.         } //else {
  2032.             // ?????
  2033.         //}
  2034.     }
  2035.  
  2036. }   // end of class
  2037. ?>